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USER'S GUIDE FOR SUBROUTINE FFQRM: A FORMAT-FREE INPUT SYSTEM 
Identification 

FFORM - A Subroutine Package Which Handles Free-Form Input 

Authors - Larry Gales and- Lougenla Anderson 



Date 



- April 1978, Center for Quantitative Science in Forestry, Fisheries 
and Wildlife, University of Washington, Seattle, Washington 98195 



Purpose 



FFORM is a portable format-free input subroutine package which simplifies 
the input of values to computer programs. It is especially suitable for the input 
of directives which control the operation of Interactive programs. Large data 
sets (e.g. more than 300 cards) are better handled by other means. 

Conventional (formatted) input requires that users conform to the exact 
specifications dictated by the program which reads it. These specifications are 
often difficult to follow, are Intolerant of errors, require that all input demanded 
by the program be present, and are peculiar to each individual program, thus requiring 
users to learn different input procedures for different programs. 

FFORM input, however, is controlled mainly by the user, not by the program, and 
features a relaxed input syntax which assigns values to program variables by name 
without regard to position or order, and with blanks or comments freely Interspersed. 
For example, the following input sets are all equivalent and assign the values 5 and 
10 to variables named TIME and VELOC, respectively, and zero out the first 10 elements 
in an array named ARRAY. Each input set, which may span more than one card, is 
terminated by a dollar sign, and comments are enclosed within slashes. 
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VELOC - 10.0, TIME - 5.0, ARRAY 10*0 $ 
ARRAY(l) - 10*0.0, TIME - 5, VELOC » 10, $ 

TIME/OF DAY/ - 5/O'CLOCK/, ARRAY » 0,0, 8*0, 
VELOC/ITY/ « lEl/MPH/ $ 
FFORM makes it easy for programs to handle default va<:.s^= ' hat users 
need input only those values which differ from their def 8Jl. I addition, the 

input procedures for all programs which use FFORM are very sIj. i d differ 

mainly in terms of the names, types, and dimensions of variables r^r- ired by 
each program. 

This write-up assumes that FFORM is already incorporated as « subroutine in 
an existing program. For a more thorough discussion of FFORM r^^M.;' to its 
programmer's guide (Anderson and Gales, 1978). 

Input Syntax 

The input for a data set consists of a sequence of [inpub-expression] 's 
(abbreviated [in-exp]) separated by commas and terminated by a dollar sign, "$" 
(used to indicate the end of input), as follows: 

[ in'-exp ] , [ in-exp ] [ in-exp ] , $ 

where the comma between the last [in-exp] and the dollar sign is optional. 
Each [in-exp] is of the form 

[name] « [value] or 

[name] [subscript-list] ■ [value-list] 

where 

[name] is the name of an input variable. It must contain one to six 
letters or digits and must start with a letter. 

Examples: ENERGY, H123, F2D 
[subscript-list] consists of one, i:wo, or three subscripts separated by 

conmias and enclosed within parentheses. 

Examples: (1)» (3» 4, 10), (6, 1) 
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If a [subscript-list] consists of more than one 
subscript then the first varies most rapidly, the 
second varies less rapidly, and the third varies 
least rapidly • 

[value-list] consists of one or more [value-expression] *s separated 

by commas. Example: 4, 16, 9*26, 2*49 

[value-expression] is either of the form [value], representing a single 

value, or [integer]* [value] indicating that [value] is to 
be repeated [integer] number of times. Example: 9*26 

[value] is either an [integer], a [real-number], a [logical- 

/ constant], or a [text-string]. 

[integer] is any number of the form d***d or -d**»d where d is 

a digit (0-9). 
Examples: 1, 473 ^ -5, 6252 

[real-number] is any number of the form n or -n where 



n = d?*»d or 

d»»»d. or 

.d»»»d or 

d»»»d.d»»»d • or 

d«»»d[exp] or 

d»»»d.[exp] or 
d»»»d.d»»»d [exp] 

and where 

[exp] » E ± d»»»d or 
Ed»»»d 



The E indicates that a number is to be multiplied 
by a power of ten. 
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Examples: 0.5, -.5, 3E+2, 3E2, 4.5E-12, 3 
[logical constant] is either T, .T., or TRUE indicating the logical 

value "true" or F, .F., or FALSE indicating the logical 
value "false". 

[text-string] consists of any string of alphanumeric symbols enclosed 

within hash marks. The hash mark symbol, "//", may not 
appear anywhere in the string itself. The length of the 
string must not exceed 68 characters as the entire 
string must appear on one card image within columns 
1 to 72. 

Examples: #THIS IS A TEXT STRING //, 

//AND SO IS THIS /*()•••#,# 1 // 
As many [in-exp]'s as desired may appear on any card, and a single [in-exp] 
or input set may span any number of cards provided that each card ends with a 
comma which separates [in-exp] 's or [value-expression] 's. 

In addition, comments may appear anywhere on a card except within a [name] 
or a [value]. Comments must be enclosed within slashes, "/", and cannot contain 
internal slashes. 

Restrictions 

The maximum number of characters in a text string is 68. 

The maximum number of different variable names within any one input set is 50. 
All input handled by FFORM must lie within columns 1 and 72, inclusive. 
All variable names are restricted to six characters or less. 

Advanced Features 

FFORM contains several advanced f eattures which are of limited use to the 
computer novice and which are described in the programmer's guide for FFORM. 
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These include an output subsystem which is fully compatible with FFORM input, 
the input/output of complex and double precision values, and a means of 
specifying sublists which provide additional control over input/output. 

Error Handling 

FFORM checks for 25 types of input errors. When an error occurs, it 
outputs an appropriate error number, underscores that part of the input card 
in error, and skips down to the end of the current data set (indicated by a 
dollar sign) . Any other error processing is left up to the program which 
calls FFORM. The error messages are listed in the Appendix. 

Sample Runs 

The listings on the next few pages contain three examples of typical 
FFORM input. The first two runs show only the input which a user might prepare 
for programs which accept FFORM directives—the programs themselves are not 
shown. Note that the hash mark symbol, which is used to delimit text 

strings, is printed out by the CDC 6400 computer as The third example 

is included mainly for the sake of completeness £ should be skipped by users 
who are not familiar with Fortran programs. It shows the complete setup for 
a typical FFORM run: system control cards (used for the NOS/BE operating 
system on a CDC 6400 computer) , a Fortran program which accepts FFORM input, 
the FFORM input itself, and the results of executing the program with the 
given data. The parameters in the FFORM routines QQINTL, QQREAD, and QQWRIT 
are explained in the programmer's guide for FFORM. 
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/ RUN It 

/ SAMPLE INPUT TO A PROGRAM INOT SHOWN) 

/ hHICH CALCULATES THE VOLUME OF A 

/ CYLINDER GIVEN ITS RADIIS AND HEIGHT* 

/ ASSUME THAT THE INPUT VARIABLES ARE i 

/ -RADIUS- (WHICH MUST BE A CREAL-NUMBERn 

/ -HEIGHT- (WHICH MUST BE A CRtAL-NUMBER 1 ) 

/ -TITLE- (WHICH MUST BE A CTEXT-STRINGl ) 

/ -FINIS- (WHICH MUST BE A CLCGICAL-C0NSTANT3 

/ -TITLE- HAY HOLD UP TO 50 CHARACTERS^ AND 

/ -FINIS- IS USED TC TERMINATE THE PROGRAM 

/ 

RADIIS - 2.45/METERS/; HEIGHT /ALSO IN METERS/ - l.C> 
TITLE • »THIS IS THE FIRST INPUT SETi* $ 

/ 

TITLE • iSECOND TIME AROUNDs^ RADIUS • 9*0^ 

HEIGHT ■ .^E-Z* 

$ 



FINIS - .T.* S 



♦fcCR 
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/ SUN 21 

/.SAKPLl INPUT TC A PROGRAM (HOT SHOWN HERE - SfcE RUN 3) 
/ kHlCH MULTIPLIES A 3 BY 3 ELEMENT ARRAY -A- BY A 
/ 3 ELEMENT VECTOR -X- YIELDING B ■ A ♦ X. ASSUME 
/ THE IhPlT VARIABLES AREt 

/ -A- (WHICH MUST CCNTAIN CiNTfeGERJ VALUES) 

/ CWHICH MUST CONTAIN CINTE6ER3 VALUES) 

/ -FINIS- (WHICH MUST BE A CL06ICAL CONSTANTl) 

/ -FINIS- IS USED TO TERMINATE THE PROGRAM 
/ 

ACi#l) • 3# A(2#l) • A(3#2) • b*tt, 

XC3) • *tb, XCl) • Zl, XC2) ■ 13, FINIS • F# $ 

/ 

XCl) • 2»4# AC1#1) • 9*t, X(3) • 1, $ 

f 

ACi#3) ■ 3*96# X(l) • 9, AC1#1) ■ 6*150# 
X(2» • 2*1&6C# S 

/ 

FIMS » T# $ 

♦ECR 
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AHULT. RUN 3 

ACCOLNT#XXXXXXXX#XXXXXXXX« 

CCrirENT. THE F0LLQUIN6 ARE SYSTEM CONTROL CARDSl 

PNF>l«0#B«LGO. 

A1TACH#BFJ-#10»BFF« 

LOAD#LGC« 

LOAD#BFF» 

£X£CL'TE#HUL«V. 

C0HHEN1. iHt FOLLOWING IS THE PROfcRAH -HULMV-* 
*EQR 

PROGRAM MULMVC INPUT* 0UTPUT#TAPE1#TAPE5»INPUT#TAPE6»0UTPUT) 

C 

C VARIABLES READ BY FREE-FORh 

C 

CDNNON// A(3#3)# X(3)# FINIS 

INTEGER A# X 

LOGICAL FINIS 

C 

C LCCAL VARIABLES 

C 

INTEGER 6(3)# ERR 

C B ■ RESULT OF MULTIPLYING A ♦ X 

C tRR ■ ERROR INDICATOR CHILL BE IGNORED IN THIS RUN) 

C 

C IMTIALIZt FREE-FORM SYSTE^ 

C 

kRlTE(l#l) 

CALL QQINTL(0#1H tlpbp ERR) 

C 

C READ AND ECHO USER-S INPUT 

C 

10 MRITE(6#11) 

CALL QQREA0(5#0#6# ERR) 
CALL QCWRITC6 ) 
IF CFINIS) STOP 

C 

C CALCULATE B • A ♦ X AND PRINT Bi 

C 

DO 30 I - 1#3 
B(I) • 0 
DO £0 J ■ 1#3 

B(I) - 6(1) * A(1#J) * X(J) 

20 CONTINUE 
30 CONTINUE 

kRlTE(6#21) (e(I)#I«l#3) 
GOTO 10 

C 

C FORMATS 
C 

1 F0RMATC21H INTEGER AC3*3)# XC3) /l^H LOGICAL FINIS % $ ) 

11 FCkHAT(39H0— CURRENT VALUES OF INPUT VARlABLESi ) 

21 F0RMATC23H0 BC1)# B(2)# BCS) ■ f 317) 
END 

♦ EOR 

/ HERE IS THE INPUT FOR RUN 3i 

/ THE ABOVE PROGRAM MULTIPLIES A 3 BY 3 

/ ELEMENT ARRAY -A- BY A 3 ELEMENT VECTOR 

/ -X- YIELDING B • A « X. ASSUHE THE INPUT VARIABLES AREl 

/ -A- (WHICH MUST CONTAIN CINTEGERl VALUES) 

/ -k- (MHICH MUST CONTAIK (INTEGER] VALUES) 
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/ -flNIS- (WHICH HUST BE A tLOMCAL C0NSTAHT3) 

/ *FIMS- IS USED TO TERHINAIE THE PROGRAM 

/ 

A(l#l) • 3, A(2#l) ■ 5*<t, A(l>3) n 3*4, 

X(3} - 46« X(l) - 21> X(2) ■ 12, FINIS - F# $ 

/ 

X(l) • 2*1,, A(l#l) ■ 9«6> X(3) - 1# S 

/ 

A(I>3) ■ 3«96# X(X) • A(1>1) • 6*150# 

XC2) - z*ioeo, % 

I 

FIMS • T* $ 

♦ tOR 

♦ EOF 
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— -CtRRENT VALUtS OF INPUT VARIABLES* ' / 

A • 3* 9, 9, ' 9i 

9> 9» '*» 

X • • 21» 13» ^6* 

FIMS • F# 

$ 

B(l)» BC2), B(3) " 36^ ASt A9u 

CLRRENT VALtES OF INPUT URlABLtS« 

^ > 6* 6» 

6> 6> 6> 

o> 

X " ^» 1» 

FIMS ■ F» 
S 

3(1), B(2)/ B(3) - "i^ !A 

— CIRRENT VALLfcS GF INPUT VARIABLLSi 

A . 150, 160, 150, 150# 

150, 150, "it* 'fe* 

<;6, 

X . 9, ICBO, 1060^ 

FlMS " F, 

i 

B(l), B(2), 6(3) " 267^20 2t)703t 267CiiC 
CIRRENT VALULS OF INPUT VAKlAELtS« 

» . 15U, 150, 15U, 15C* 

150, 150, 9t, 9t, 

X . 9* UeO, 1080, 

FINIS • T, 

1 

tCR 
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APPENDIX 



ERROR MESSAGES 





1 


ILLEGAL CHARACTER 


2 


UNRECOGNIZABLE SYNTACTIC SYMBOL 


3 


END-OF-CARD EXPECTED 


4 


RESERVED WORD EXPECTED 


5 


VARIABLE NAME EXPECTED 


6 


SYMBOL TABLE OVERFLOW 


7 


DUPLICATE DECLARATION 


8 


INTEGER SUBSCRIPT EXPECTED 


9 


LPAREN EXPECTED 


10 


RPAREN EXPECTED 


11 


lONAME ARGUMENT TO SUBROUTINE QQINTL DOES NOT MATCH ANY lO-LIST NAME 


12 


UNDECLARED VARIABLE NAME 


13 


EQUAL SIGN EXPECTED 


14 


VARIABLE DOES NOT APPEAR ON CURRENT lO-LIST 


15 


ONE OF SUBSCRIPTS EXCEEDS DECLARED SUBSCRIPT 


16 


COMMA EXPECTED 


17 


REPEAT VALUE MUST BE AN INTEGER 


18 


INTEGER VALUE EXPECTED 


1 Q 


ARRAY OUT OF BOUNDS 


20 


REAL VALUE EXPECTED 


21 


TEXT VALUE EXPECTED 


22 


LOGICAL VALUE EXPECTED 


23 


DOUBLE PRECISION VALUE EXPECTED 


24 


COMPLEX VALUE EXPECTED ^ 


25 


END-OF-FXLE MARK EXPECTED 



